<html>
<head>
<title>Decomb Plugin for Avisynth 2.5</title>
<link rel="stylesheet" type="text/css" href="../../avisynth.css">
<!--
Automatically generated, don't change:
$Id: decombtutorial.htm,v 1.1 2005/10/03 16:31:31 macpaille Exp $
-->
</head>

<body>
<h1 align=center>Decomb Plugin for Avisynth<br>
(Version 5.2.1)<br>
Tutorial</h1>

<h2 align=center>by Donald A. Graft</h2>
<p><hr><p>
<h2>Table of Contents</h2>

<ul>
 <li><a href="#introduction">Introduction</a></li>
 <li><a href="#telecide">Telecide()</a></li>
 <ul>
  <li><a href="#field order">Step 1. Determine and Set the Field Order</a>
  <li><a href="#pattern">Step 2. Set up Pattern Guidance If Appropriate</a>
  <li><a href="#postprocessing">Step 3. Set up Postprocessing</a>
 </ul>
 <li><a href="#decimate">Decimate()</a></li>
 <ul>
  <li><a href="#decimation">Step 4. Setting Up Decimation</a>
 </ul>
 <li><a href="#refinements">Refinements</a></li>
</ul>

<p><hr size=2 width="100%" align=center>
<h2><a name=introduction>Introduction</a></h2>

<p>This document is a tutorial for Decomb. It provides a cookbook procedure
for applying Telecide() and Decimate() correctly to process a given clip. It doesn't cover
FieldDeinterlace() as that is fairly easy to figure out from the Decomb Reference Manual.
<p>
Please refer to the
accompanying Decomb Reference Manual for a detailed description of Decomb
and it parameters.</p>
<p>
<hr size=2 width="100%" align=center>

<h2><a name=telecide>Telecide()</a></h2>

<p>Telecide() recovers
progressive frames (by finding and aligning matching fields).
Do not use Telecide() on streams that do not contain telecined
progressive frames, such as pure interlaced video.</p>

<a name="field order"></a>
<h3>Step 1. Determine and Set the Field Order</h3>
<p>It is essential to set the field order properly for correct rendering. The field order is
set using the mandatory parameter <i>order</i>. Set order=1 for top field first; set order=0
for bottom field first. Because setting it correctly is so important, you are strongly
encouraged not to make assumptions about the field order of a clip, but rather to verify
the field order using the following procedure.</p>
<p>
To determine the field order, make an Avisynth script that serves the raw clip without any
processing. If it were an AVI, then just AviSource() would be used. For our examples, we'll
use AviSource(). Add a script line to separate the fields using top field first, as follows:
<pre>AviSource(&quot;your_clip.avi&quot;)
AssumeTFF().SeparateFields()</pre>
<p>Now serve the script into VirtualDub and find an area with motion. Single step forward through
the motion. Note whether the motion progresses always forward as it should, or whether it jumps
back and forth as it proceeds. For example, if the field order is wrong,
an object moving steadily from left to right would move right, then jump back left a little, then
move right again, etc. If the field order is correct, it moves steadily to the right.</P>
<p>If the motion is correct with AssumeTFF().SeparateFields(), then your field order is top
field first and you must set order=1. If the motion is incorrect, then your field order is
bottom field first and you must set order=0. If you are want to double check things, you can use
AssumeBFF.SeparateFields() to check correct operation for bottom field first.</p>
<p>Let's assume we have a top field first clip in the following steps. You would of course use
the correct field order for your clip. So far, then, our script is as follows:
<pre>AviSource(&quot;your_clip.avi&quot;)
Telecide(order=1)</pre>

<h3><a name="pattern">Step 2. Set up Pattern Guidance If Appropriate</a></h3>
<p>Often you know from the nature of a clip what telecining pattern (if any) is used and therefore what
the pattern of field matches should be. Telecide()'s pattern guidance feature uses that
information to improve the field matching. Pattern guidance is controlled by the optional
<i>guide</i> parameter. It has 4 possible values: guide=0 means disable pattern guidance;
guide=1 means use 3:2 pulldown guidance (24fps->30fps); guide=2 means use 2:2 guidance (PAL);
and guide=3 means use 3:2:3:2:2 guidance (25fps->30fps).
<p>
First decide if your source clip is PAL. If it is, and if it has progressive content, you can
almost invariably set guide=2 to use PAL pattern guidance. Of course, if your clip does not have
progressive content, it will not help you, and you shouldn't be using Telecide() at all! So for PAL,
we can skip to Step 3 with our script looking this so far:
<pre>AviSource(&quot;your_clip.avi&quot;)
Telecide(order=1,guide=2)</pre>
<p>
If we have an NTSC 29.97fps or 30fps source clip, things are trickier.
First we have to determine whether the clip
contains 3:2 pulldown material. There are several tests we can apply. First, serve the clip raw
(no Decomb or other processing) into VirtualDub. Then step through the frames in motion areas. If
you see a repeating pattern of 3 clean frames followed by 2 interlaced frames, that is 3:2 pulldown.
Typically, movies will use 3:2 pulldown.
<p>Looking for the 3:2 pattern as described above is not foolproof, because for animations there are
duplicate frames that can make it hard to see a clear 3:2 pattern.
<p>Second, you can serve the following script into VirtualDub and see what Telecide() reports about it
(remember to use the correct field order as you determined it above).
<pre>
AviSource(&quot;your_clip.avi&quot;)
Telecide(order=1,guide=1,post=0,show=true)
</pre>
Serve this into VirtualDub and step through several typical sections of your clip. If Telecide() reports
"in-pattern", or "in-pattern*", then it is locking onto 3:2 pulldown. If it reports "out-of-pattern"
or continuously jumps in and out of pattern lock, then it is not locking onto a consistent 3:2 pattern.
<p>
If you determine that your clip has a lot of 3:2 content, then you should go ahead and set guide=1.
If there is not a lot of 3:2 content, or you have any doubts about the nature of the clip, then you
should set guide=0. We will assume that we have a lot of 3:2 content for the next steps. Therefore, our
script so far looks like this:
<pre>AviSource(&quot;your_clip.avi&quot;)
Telecide(order=1,guide=1)</pre>
<h3><a name="postprocessing">Step 3. Set up Postprocessing</a></h3>
<p>Postprocessing is the process by which frames that come out of the field matching process still
combed can be detected and deinterlaced. The postprocessing modes are controlled by the <i>post</i>
parameter: post=0 means disable postprocessing; post=1 means calculate the metrics but don't deinterlace;
post=2 means calculate the metrics and deinterlace accordingly; and post=3 means
calculate the metrics, deinterlace accordingly, and show a deinterlacing motion map for frames that
are detected as combed. There are two more advanced modes as well; please refer to the reference manual for
details.
<p>
We will adopt a standard procedure for setting up postprocessing. First, we will enable the metrics
and show them as follows (note we are carrying forward previously determined settings -- you would
use the ones you earlier determined for <i>order</i> and <i>guide</i>):
<pre>AviSource(&quot;your_clip.avi&quot;)
Telecide(order=1,guide=1,post=3,vthresh=25,show=true)</pre>
Serve this into VirtualDub and play through the clip while examining frames and the displayed
<i>vmetric</i> values. The value that applies to the frame as matched is the one in brackets that
starts with "chosen=", e.g., "[chosen=27]". Let's just call that the <i>vmetric</i> value.
Any <i>vmetric</i> value greater than <i>vthresh</i>
defines the frame as interlaced. 
You want to find the <i>vthresh</i> value that correctly distinguishes combed frames from non-combed frames
for your clip. You'll easily be able to identify the frames thought to be combed because a) the <i>vmetric</i>
value will be greater than <i>vthresh</i>, b) the progressive/interlaced indicator will say interlaced, and c) the
frame will have a white deinterlacing motion map overlayed on it. There's no way you'll miss them!
<p>
Your chosen <i>vthresh</i> may not be perfect and if it is not you should err on the side of caution.
It's better to catch some progressive frames than to miss some combed ones.
<p>
Let's suppose that our <i>vthresh</i> value that distinguishes combed from non-combed frames is 30.
Now create the following script with post=2 (carry over your determined previous settings, as always):
<pre>AviSource(&quot;your_clip.avi&quot;)
Telecide(order=1,guide=1,post=2,vthresh=30,show=true)</pre>
Serve this and play it into VirtualDub. As you step through you should see the progressive frames
passing through untouched while the combed ones ones are deinterlaced.
<p>
If you are not happy with the deinterlacing of the combed frames and want them "hit a little harder",
you can reduce the <i>dthresh</i> parameter. Also, if you prefer interpolation to blending for the
combed areas, you can change the <i>blend</i> parameter. Refer to the reference manual for the
proper use of these parameters.
<p>
Our script so far then is:
<pre>AviSource(&quot;your_clip.avi&quot;)
Telecide(order=1,guide=1,post=2,vthresh=30)</pre>
<p>There are two more important things to say about postprocessing before we move on. First, there is a subtle
difference between post=2 and post=4 which might affect you. The reference manual describes the
differences in detail. Setting post=2 will often avoid making gross frame blends at scene changes, but it
can make deinterlaced video sequences jerky. Setting post=4 retains the smoothness of deinterlaced sequences,
but may make frame blends at scene changes.</p>
<p>Second, you may find that you need different <i>vthresh</i> values for different parts of your clip. If so,
use Telecide's manual override capability to specify values for different frame ranges as needed. Refer to the
reference manual for details.
</p>
<h2><a name=decimate>Decimate()</a></h2>
<p>As a side effect of performing field matching for 3:2 pulldown, Telecide() emits duplicate frames and
leaves the clip at its original frame rate. Decimate() detects and removes these duplicates and sets the
frame rate down appropriately.
<h3><a name="decimation">Step 4. Set up Decimation</a></h3>
<p>If your clip is PAL, you do not require decimation and you are finished!
<p>If your clip has 3:2 pulldown, you will need to decimate the clip. Simply add a call to Decimate().
Our final script then looks like this:
<pre>AviSource(&quot;your_clip.avi&quot;)
Telecide(order=1,guide=1,post=2,vthresh=30)
Decimate()</pre>
One thing to be aware of is that you may not always want to decimate 30fps material. For example, if
your clip is a hybrid of 3:2 progressive and normal interlaced video, if you decimate it you'll make the
video portions jerky. Often with such clips it is better to leave them at their original frame rate
by omitting Decimate().
<h2><a name="refinements">Refinements</a></h2>
<p>This manual has described only the basic parameters and procedures required to
quickly master Decomb. There are many more parameters that you can use to adapt to unusual and difficult
situations. Please refer to the Decomb Reference manual to begin exploring this additional
functionality.
<p>Here is one example of a refinement so you'll understand what I am talking about: Suppose you
have a noisy off-air capture and you are experiencing matching failures. You can add some extra
noise tolerance to Telecide() by increasing the value of the
<i>nt</i> parameter. You will find many such little gems in the
Reference Manual. It makes great bathtub reading.
<p>
<hr size=2 width="100%" align=center>

<p>Copyright &copy; 2003, Donald A. Graft, All Rights Reserved.</p>

<p>For updates and other filters/tools, visit my web site:<br>
<a href="http://shelob.mordor.net/dgraft/" target="_top">http://neuron2.net/</a>
</p>

<p><kbd>$Date: 2005/10/03 16:31:31 $</kbd></p>

</body>

</html>
